Declarative Setup

Argo CD applications, projects and settings can be defined declaratively using Kubernetes manifests. These can be updated using kubectl apply, without needing to touch the argocd command-line tool.

Quick Reference

All resources, including Application and AppProject specs, have to be installed in the Argo CD namespace (by default argocd).

Atomic configuration

Sample FileResource NameKindDescription
argocd-cm.yamlargocd-cmConfigMapGeneral Argo CD configuration
argocd-repositories.yamlmy-private-repo / istio-helm-repo / private-helm-repo / private-repoSecretsSample repository connection details
argocd-repo-creds.yamlargoproj-https-creds / argoproj-ssh-creds / github-creds / github-enterprise-credsSecretsSample repository credential templates
argocd-cmd-params-cm.yamlargocd-cmd-params-cmConfigMapArgo CD env variables configuration
argocd-secret.yamlargocd-secretSecretUser Passwords, Certificates (deprecated), Signing Key, Dex secrets, Webhook secrets
argocd-rbac-cm.yamlargocd-rbac-cmConfigMapRBAC Configuration
argocd-tls-certs-cm.yamlargocd-tls-certs-cmConfigMapCustom TLS certificates for connecting Git repositories via HTTPS (v1.2 and later)
argocd-ssh-known-hosts-cm.yamlargocd-ssh-known-hosts-cmConfigMapSSH known hosts data for connecting Git repositories via SSH (v1.2 and later)

For each specific kind of ConfigMap and Secret resource, there is only a single supported resource name (as listed in the above table) - if you need to merge things you need to do it before creating them.

A note about ConfigMap resources

Be sure to annotate your ConfigMap resources using the label app.kubernetes.io/part-of: argocd, otherwise Argo CD will not be able to use them.

Multiple configuration objects

Sample FileKindDescription
application.yamlApplicationExample application spec
project.yamlAppProjectExample project spec
-SecretRepository credentials

For Application and AppProject resources, the name of the resource equals the name of the application or project within Argo CD. This also means that application and project names are unique within a given Argo CD installation - you cannot have the same application name for two different applications.

Applications

The Application CRD is the Kubernetes resource object representing a deployed application instance in an environment. It is defined by two key pieces of information:

  • source reference to the desired state in Git (repository, revision, path, environment)
  • destination reference to the target cluster and namespace. For the cluster one of server or name can be used, but not both (which will result in an error). Under the hood when the server is missing, it is calculated based on the name and used for any operations.

A minimal Application spec is as follows:

  1. apiVersion: argoproj.io/v1alpha1
  2. kind: Application
  3. metadata:
  4. name: guestbook
  5. namespace: argocd
  6. spec:
  7. project: default
  8. source:
  9. repoURL: https://github.com/argoproj/argocd-example-apps.git
  10. targetRevision: HEAD
  11. path: guestbook
  12. destination:
  13. server: https://kubernetes.default.svc
  14. namespace: guestbook

See application.yaml for additional fields. As long as you have completed the first step of Getting Started, you can apply this with kubectl apply -n argocd -f application.yaml and Argo CD will start deploying the guestbook application.

Note

The namespace must match the namespace of your Argo CD instance - typically this is argocd.

Note

When creating an application from a Helm repository, the chart attribute must be specified instead of the path attribute within spec.source.

  1. spec:
  2. source:
  3. repoURL: https://argoproj.github.io/argo-helm
  4. chart: argo

Warning

By default, deleting an application will not perform a cascade delete, which would delete its resources. You must add the finalizer if you want this behaviour - which you may well not want.

  1. metadata:
  2. finalizers:
  3. - resources-finalizer.argocd.argoproj.io

App of Apps

You can create an app that creates other apps, which in turn can create other apps. This allows you to declaratively manage a group of apps that can be deployed and configured in concert.

See cluster bootstrapping.

Projects

The AppProject CRD is the Kubernetes resource object representing a logical grouping of applications. It is defined by the following key pieces of information:

  • sourceRepos reference to the repositories that applications within the project can pull manifests from.
  • destinations reference to clusters and namespaces that applications within the project can deploy into (don’t use the name field, only the server field is matched).
  • roles list of entities with definitions of their access to resources within the project.

An example spec is as follows:

  1. apiVersion: argoproj.io/v1alpha1
  2. kind: AppProject
  3. metadata:
  4. name: my-project
  5. namespace: argocd
  6. # Finalizer that ensures that project is not deleted until it is not referenced by any application
  7. finalizers:
  8. - resources-finalizer.argocd.argoproj.io
  9. spec:
  10. description: Example Project
  11. # Allow manifests to deploy from any Git repos
  12. sourceRepos:
  13. - '*'
  14. # Only permit applications to deploy to the guestbook namespace in the same cluster
  15. destinations:
  16. - namespace: guestbook
  17. server: https://kubernetes.default.svc
  18. # Deny all cluster-scoped resources from being created, except for Namespace
  19. clusterResourceWhitelist:
  20. - group: ''
  21. kind: Namespace
  22. # Allow all namespaced-scoped resources to be created, except for ResourceQuota, LimitRange, NetworkPolicy
  23. namespaceResourceBlacklist:
  24. - group: ''
  25. kind: ResourceQuota
  26. - group: ''
  27. kind: LimitRange
  28. - group: ''
  29. kind: NetworkPolicy
  30. # Deny all namespaced-scoped resources from being created, except for Deployment and StatefulSet
  31. namespaceResourceWhitelist:
  32. - group: 'apps'
  33. kind: Deployment
  34. - group: 'apps'
  35. kind: StatefulSet
  36. roles:
  37. # A role which provides read-only access to all applications in the project
  38. - name: read-only
  39. description: Read-only privileges to my-project
  40. policies:
  41. - p, proj:my-project:read-only, applications, get, my-project/*, allow
  42. groups:
  43. - my-oidc-group
  44. # A role which provides sync privileges to only the guestbook-dev application, e.g. to provide
  45. # sync privileges to a CI system
  46. - name: ci-role
  47. description: Sync privileges for guestbook-dev
  48. policies:
  49. - p, proj:my-project:ci-role, applications, sync, my-project/guestbook-dev, allow
  50. # NOTE: JWT tokens can only be generated by the API server and the token is not persisted
  51. # anywhere by Argo CD. It can be prematurely revoked by removing the entry from this list.
  52. jwtTokens:
  53. - iat: 1535390316

Repositories

Note

Some Git hosters - notably GitLab and possibly on-premise GitLab instances as well - require you to specify the .git suffix in the repository URL, otherwise they will send a HTTP 301 redirect to the repository URL suffixed with .git. Argo CD will not follow these redirects, so you have to adjust your repository URL to be suffixed with .git.

Repository details are stored in secrets. To configure a repo, create a secret which contains repository details. Consider using bitnami-labs/sealed-secrets to store an encrypted secret definition as a Kubernetes manifest. Each repository must have a url field and, depending on whether you connect using HTTPS, SSH, or GitHub App, username and password (for HTTPS), sshPrivateKey (for SSH), or githubAppPrivateKey (for GitHub App).

Example for HTTPS:

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4. name: private-repo
  5. namespace: argocd
  6. labels:
  7. argocd.argoproj.io/secret-type: repository
  8. stringData:
  9. url: https://github.com/argoproj/private-repo
  10. password: my-password
  11. username: my-username

Example for SSH:

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4. name: private-repo
  5. namespace: argocd
  6. labels:
  7. argocd.argoproj.io/secret-type: repository
  8. stringData:
  9. url: git@github.com:argoproj/my-private-repository
  10. sshPrivateKey: |
  11. -----BEGIN OPENSSH PRIVATE KEY-----
  12. ...
  13. -----END OPENSSH PRIVATE KEY-----

Example for GitHub App:

  1. kind: Secret
  2. metadata:
  3. name: github-repo
  4. namespace: argocd
  5. labels:
  6. argocd.argoproj.io/secret-type: repository
  7. stringData:
  8. repo: https://github.com/argoproj/my-private-repository
  9. githubAppID: 1
  10. githubAppInstallationID: 2
  11. githubAppPrivateKeySecret: |
  12. -----BEGIN OPENSSH PRIVATE KEY-----
  13. ...
  14. -----END OPENSSH PRIVATE KEY-----
  15. ---
  16. apiVersion: v1
  17. kind: Secret
  18. metadata:
  19. name: github-enterprise-repo
  20. namespace: argocd
  21. labels:
  22. argocd.argoproj.io/secret-type: repository
  23. stringData:
  24. repo: https://ghe.example.com/argoproj/my-private-repository
  25. githubAppID: 1
  26. githubAppInstallationID: 2
  27. githubAppEnterpriseBaseUrl: https://ghe.example.com/api/v3
  28. githubAppPrivateKeySecret: |
  29. -----BEGIN OPENSSH PRIVATE KEY-----
  30. ...
  31. -----END OPENSSH PRIVATE KEY-----

Tip

The Kubernetes documentation has instructions for creating a secret containing a private key.

Repository Credentials

If you want to use the same credentials for multiple repositories, you can configure credential templates. Credential templates can carry the same credentials information as repositories.

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4. name: first-repo
  5. namespace: argocd
  6. labels:
  7. argocd.argoproj.io/secret-type: repository
  8. stringData:
  9. url: https://github.com/argoproj/private-repo
  10. ---
  11. apiVersion: v1
  12. kind: Secret
  13. metadata:
  14. name: second-repo
  15. namespace: argocd
  16. labels:
  17. argocd.argoproj.io/secret-type: repository
  18. stringData:
  19. url: https://github.com/argoproj/other-private-repo
  20. ---
  21. apiVersion: v1
  22. kind: Secret
  23. metadata:
  24. name: private-repo-creds
  25. namespace: argocd
  26. labels:
  27. argocd.argoproj.io/secret-type: repo-creds
  28. stringData:
  29. url: https://github.com/argoproj
  30. password: my-password
  31. username: my-username

In the above example, every repository accessed via HTTPS whose URL is prefixed with https://github.com/argoproj would use a username stored in the key username and a password stored in the key password of the secret private-repo-creds for connecting to Git.

In order for Argo CD to use a credential template for any given repository, the following conditions must be met:

  • The repository must either not be configured at all, or if configured, must not contain any credential information (i.e. contain none of sshPrivateKey, username, password )
  • The URL configured for a credential template (e.g. https://github.com/argoproj) must match as prefix for the repository URL (e.g. https://github.com/argoproj/argocd-example-apps).

Note

Matching credential template URL prefixes is done on a best match effort, so the longest (best) match will take precedence. The order of definition is not important, as opposed to pre v1.4 configuration.

The following keys are valid to refer to credential secrets:

SSH repositories

  • sshPrivateKey refers to the SSH private key for accessing the repositories

HTTPS repositories

  • username and password refer to the username and/or password for accessing the repositories
  • tlsClientCertData and tlsClientCertKey refer to secrets where a TLS client certificate (tlsClientCertData) and the corresponding private key tlsClientCertKey are stored for accessing the repositories

GitHub App repositories

  • githubAppPrivateKey refers to the GitHub App private key for accessing the repositories
  • githubAppID refers to the GitHub Application ID for the application you created.
  • githubAppInstallationID refers to the Installation ID of the GitHub app you created and installed.
  • githubAppEnterpriseBaseUrl refers to the base api URL for GitHub Enterprise (e.g. https://ghe.example.com/api/v3)
  • tlsClientCertData and tlsClientCertKey refer to secrets where a TLS client certificate (tlsClientCertData) and the corresponding private key tlsClientCertKey are stored for accessing GitHub Enterprise if custom certificates are used.

Repositories using self-signed TLS certificates (or are signed by custom CA)

v1.2 or later

You can manage the TLS certificates used to verify the authenticity of your repository servers in a ConfigMap object named argocd-tls-certs-cm. The data section should contain a map, with the repository server’s hostname part (not the complete URL) as key, and the certificate(s) in PEM format as data. So, if you connect to a repository with the URL https://server.example.com/repos/my-repo, you should use server.example.com as key. The certificate data should be either the server’s certificate (in case of self-signed certificate) or the certificate of the CA that was used to sign the server’s certificate. You can configure multiple certificates for each server, e.g. if you are having a certificate roll-over planned.

If there are no dedicated certificates configured for a repository server, the system’s default trust store is used for validating the server’s repository. This should be good enough for most (if not all) public Git repository services such as GitLab, GitHub and Bitbucket as well as most privately hosted sites which use certificates from well-known CAs, including Let’s Encrypt certificates.

An example ConfigMap object:

  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4. name: argocd-tls-certs-cm
  5. namespace: argocd
  6. labels:
  7. app.kubernetes.io/name: argocd-cm
  8. app.kubernetes.io/part-of: argocd
  9. data:
  10. server.example.com: |
  11. -----BEGIN CERTIFICATE-----
  12. MIIF1zCCA7+gAwIBAgIUQdTcSHY2Sxd3Tq/v1eIEZPCNbOowDQYJKoZIhvcNAQEL
  13. BQAwezELMAkGA1UEBhMCREUxFTATBgNVBAgMDExvd2VyIFNheG9ueTEQMA4GA1UE
  14. BwwHSGFub3ZlcjEVMBMGA1UECgwMVGVzdGluZyBDb3JwMRIwEAYDVQQLDAlUZXN0
  15. c3VpdGUxGDAWBgNVBAMMD2Jhci5leGFtcGxlLmNvbTAeFw0xOTA3MDgxMzU2MTda
  16. Fw0yMDA3MDcxMzU2MTdaMHsxCzAJBgNVBAYTAkRFMRUwEwYDVQQIDAxMb3dlciBT
  17. YXhvbnkxEDAOBgNVBAcMB0hhbm92ZXIxFTATBgNVBAoMDFRlc3RpbmcgQ29ycDES
  18. MBAGA1UECwwJVGVzdHN1aXRlMRgwFgYDVQQDDA9iYXIuZXhhbXBsZS5jb20wggIi
  19. MA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQCv4mHMdVUcafmaSHVpUM0zZWp5
  20. NFXfboxA4inuOkE8kZlbGSe7wiG9WqLirdr39Ts+WSAFA6oANvbzlu3JrEQ2CHPc
  21. CNQm6diPREFwcDPFCe/eMawbwkQAPVSHPts0UoRxnpZox5pn69ghncBR+jtvx+/u
  22. P6HdwW0qqTvfJnfAF1hBJ4oIk2AXiip5kkIznsAh9W6WRy6nTVCeetmIepDOGe0G
  23. ZJIRn/OfSz7NzKylfDCat2z3EAutyeT/5oXZoWOmGg/8T7pn/pR588GoYYKRQnp+
  24. YilqCPFX+az09EqqK/iHXnkdZ/Z2fCuU+9M/Zhrnlwlygl3RuVBI6xhm/ZsXtL2E
  25. Gxa61lNy6pyx5+hSxHEFEJshXLtioRd702VdLKxEOuYSXKeJDs1x9o6cJ75S6hko
  26. Ml1L4zCU+xEsMcvb1iQ2n7PZdacqhkFRUVVVmJ56th8aYyX7KNX6M9CD+kMpNm6J
  27. kKC1li/Iy+RI138bAvaFplajMF551kt44dSvIoJIbTr1LigudzWPqk31QaZXV/4u
  28. kD1n4p/XMc9HYU/was/CmQBFqmIZedTLTtK7clkuFN6wbwzdo1wmUNgnySQuMacO
  29. gxhHxxzRWxd24uLyk9Px+9U3BfVPaRLiOPaPoC58lyVOykjSgfpgbus7JS69fCq7
  30. bEH4Jatp/10zkco+UQIDAQABo1MwUTAdBgNVHQ4EFgQUjXH6PHi92y4C4hQpey86
  31. r6+x1ewwHwYDVR0jBBgwFoAUjXH6PHi92y4C4hQpey86r6+x1ewwDwYDVR0TAQH/
  32. BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAgEAFE4SdKsX9UsLy+Z0xuHSxhTd0jfn
  33. Iih5mtzb8CDNO5oTw4z0aMeAvpsUvjJ/XjgxnkiRACXh7K9hsG2r+ageRWGevyvx
  34. CaRXFbherV1kTnZw4Y9/pgZTYVWs9jlqFOppz5sStkfjsDQ5lmPJGDii/StENAz2
  35. XmtiPOgfG9Upb0GAJBCuKnrU9bIcT4L20gd2F4Y14ccyjlf8UiUi192IX6yM9OjT
  36. +TuXwZgqnTOq6piVgr+FTSa24qSvaXb5z/mJDLlk23npecTouLg83TNSn3R6fYQr
  37. d/Y9eXuUJ8U7/qTh2Ulz071AO9KzPOmleYPTx4Xty4xAtWi1QE5NHW9/Ajlv5OtO
  38. OnMNWIs7ssDJBsB7VFC8hcwf79jz7kC0xmQqDfw51Xhhk04kla+v+HZcFW2AO9so
  39. 6ZdVHHQnIbJa7yQJKZ+hK49IOoBR6JgdB5kymoplLLiuqZSYTcwSBZ72FYTm3iAr
  40. jzvt1hxpxVDmXvRnkhRrIRhK4QgJL0jRmirBjDY+PYYd7bdRIjN7WNZLFsgplnS8
  41. 9w6CwG32pRlm0c8kkiQ7FXA6BYCqOsDI8f1VGQv331OpR2Ck+FTv+L7DAmg6l37W
  42. +LB9LGh4OAp68ImTjqf6ioGKG0RBSznwME+r4nXtT1S/qLR6ASWUS4ViWRhbRlNK
  43. XWyb96wrUlv+E8I=
  44. -----END CERTIFICATE-----

Note

The argocd-tls-certs-cm ConfigMap will be mounted as a volume at the mount path /app/config/tls in the pods of argocd-server and argocd-repo-server. It will create files for each data key in the mount path directory, so above example would leave the file /app/config/tls/server.example.com, which contains the certificate data. It might take a while for changes in the ConfigMap to be reflected in your pods, depending on your Kubernetes configuration.

SSH known host public keys

If you are connecting repositories via SSH, Argo CD will need to know the SSH known hosts public key of the repository servers. You can manage the SSH known hosts data in the ConfigMap named argocd-ssh-known-hosts-cm. This ConfigMap contains a single key/value pair, with ssh_known_hosts as the key and the actual public keys of the SSH servers as data. As opposed to TLS configuration, the public key(s) of each single repository server Argo CD will connect via SSH must be configured, otherwise the connections to the repository will fail. There is no fallback. The data can be copied from any existing ssh_known_hosts file, or from the output of the ssh-keyscan utility. The basic format is <servername> <keydata>, one entry per line.

An example ConfigMap object:

  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4. name: argocd-ssh-known-hosts-cm
  5. namespace: argocd
  6. labels:
  7. app.kubernetes.io/name: argocd-cm
  8. app.kubernetes.io/part-of: argocd
  9. data:
  10. ssh_known_hosts: |
  11. bitbucket.org ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAubiN81eDcafrgMeLzaFPsw2kNvEcqTKl/VqLat/MaB33pZy0y3rJZtnqwR2qOOvbwKZYKiEO1O6VqNEBxKvJJelCq0dTXWT5pbO2gDXC6h6QDXCaHo6pOHGPUy+YBaGQRGuSusMEASYiWunYN0vCAI8QaXnWMXNMdFP3jHAJH0eDsoiGnLPBlBp4TNm6rYI74nMzgz3B9IikW4WVK+dc8KZJZWYjAuORU3jc1c/NPskD2ASinf8v3xnfXeukU0sJ5N6m5E8VLjObPEO+mN2t/FZTMZLiFqPWc/ALSqnMnnhwrNi2rbfg/rd/IpL8Le3pSBne8+seeFVBoGqzHM9yXw==
  12. github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==
  13. gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFSMqzJeV9rUzU4kWitGjeR4PWSa29SPqJ1fVkhtj3Hw9xjLVXVYrU9QlYWrOLXBpQ6KWjbjTDTdDkoohFzgbEY=
  14. gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
  15. gitlab.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9
  16. ssh.dev.azure.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H
  17. vs-ssh.visualstudio.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H
  18. github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
  19. github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl

Note

The argocd-ssh-known-hosts-cm ConfigMap will be mounted as a volume at the mount path /app/config/ssh in the pods of argocd-server and argocd-repo-server. It will create a file ssh_known_hosts in that directory, which contains the SSH known hosts data used by Argo CD for connecting to Git repositories via SSH. It might take a while for changes in the ConfigMap to be reflected in your pods, depending on your Kubernetes configuration.

Configure repositories with proxy

Proxy for your repository can be specified in the proxy field of the repository secret, along with other repository configurations. Argo CD uses this proxy to access the repository. Argo CD looks for the standard proxy environment variables in the repository server if the custom proxy is absent.

An example repository with proxy:

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4. name: private-repo
  5. namespace: argocd
  6. labels:
  7. argocd.argoproj.io/secret-type: repository
  8. stringData:
  9. url: https://github.com/argoproj/private-repo
  10. proxy: https://proxy-server-url:8888
  11. password: my-password
  12. username: my-username

Legacy behaviour

In Argo CD version 2.0 and earlier, repositories where stored as part of the argocd-cm config map. For backward-compatibility, Argo CD will still honor repositories in the config map, but this style of repository configuration is deprecated and support for it will be removed in a future version.

  1. apiVersion: v1
  2. kind: ConfigMap
  3. data:
  4. repositories: |
  5. - url: https://github.com/argoproj/my-private-repository
  6. passwordSecret:
  7. name: my-secret
  8. key: password
  9. usernameSecret:
  10. name: my-secret
  11. key: username
  12. repository.credentials: |
  13. - url: https://github.com/argoproj
  14. passwordSecret:
  15. name: my-secret
  16. key: password
  17. usernameSecret:
  18. name: my-secret
  19. key: username
  20. ---
  21. apiVersion: v1
  22. kind: Secret
  23. metadata:
  24. name: my-secret
  25. namespace: argocd
  26. stringData:
  27. password: my-password
  28. username: my-username

Clusters

Cluster credentials are stored in secrets same as repositories or repository credentials. Each secret must have label argocd.argoproj.io/secret-type: cluster.

The secret data must include following fields:

  • name - cluster name
  • server - cluster api server url
  • namespaces - optional comma-separated list of namespaces which are accessible in that cluster. Cluster level resources would be ignored if namespace list is not empty.
  • config - JSON representation of following data structure:
  1. # Basic authentication settings
  2. username: string
  3. password: string
  4. # Bearer authentication settings
  5. bearerToken: string
  6. # IAM authentication configuration
  7. awsAuthConfig:
  8. clusterName: string
  9. roleARN: string
  10. # Configure external command to supply client credentials
  11. # See https://godoc.org/k8s.io/client-go/tools/clientcmd/api#ExecConfig
  12. execProviderConfig:
  13. command: string
  14. args: [
  15. string
  16. ]
  17. env: {
  18. key: value
  19. }
  20. apiVersion: string
  21. installHint: string
  22. # Transport layer security configuration settings
  23. tlsClientConfig:
  24. # PEM-encoded bytes (typically read from a client certificate file).
  25. caData: string
  26. # PEM-encoded bytes (typically read from a client certificate file).
  27. certData: string
  28. # Server should be accessed without verifying the TLS certificate
  29. insecure: boolean
  30. # PEM-encoded bytes (typically read from a client certificate key file).
  31. keyData: string
  32. # ServerName is passed to the server for SNI and is used in the client to check server
  33. # certificates against. If ServerName is empty, the hostname used to contact the
  34. # server is used.
  35. serverName: string

Note that if you specify a command to run under execProviderConfig, that command must be available in the Argo CD image. See BYOI (Build Your Own Image).

Cluster secret example:

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4. name: mycluster-secret
  5. labels:
  6. argocd.argoproj.io/secret-type: cluster
  7. type: Opaque
  8. stringData:
  9. name: mycluster.com
  10. server: https://mycluster.com
  11. config: |
  12. {
  13. "bearerToken": "<authentication token>",
  14. "tlsClientConfig": {
  15. "insecure": false,
  16. "caData": "<base64 encoded certificate>"
  17. }
  18. }

Helm Chart Repositories

Non standard Helm Chart repositories have to be registered explicitly. Each repository must have url, type and name fields. For private Helm repos you may need to configure access credentials and HTTPS settings using username, password, tlsClientCertData and tlsClientCertKey fields.

Example:

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4. name: istio
  5. namespace: argocd
  6. labels:
  7. argocd.argoproj.io/secret-type: repository
  8. stringData:
  9. name: istio.io
  10. url: https://storage.googleapis.com/istio-prerelease/daily-build/master-latest-daily/charts
  11. type: helm
  12. ---
  13. apiVersion: v1
  14. kind: Secret
  15. metadata:
  16. name: argo-helm
  17. namespace: argocd
  18. labels:
  19. argocd.argoproj.io/secret-type: repository
  20. stringData:
  21. name: argo
  22. url: https://argoproj.github.io/argo-helm
  23. type: helm
  24. username: my-username
  25. password: my-password
  26. tlsClientCertData: ...
  27. tlsClientCertKey: ...

Resource Exclusion/Inclusion

Resources can be excluded from discovery and sync so that Argo CD is unaware of them. For example, events.k8s.io and metrics.k8s.io are always excluded. Use cases:

  • You have temporal issues and you want to exclude problematic resources.
  • There are many of a kind of resources that impacts Argo CD’s performance.
  • Restrict Argo CD’s access to certain kinds of resources, e.g. secrets. See security.md#cluster-rbac.

To configure this, edit the argcd-cm config map:

  1. kubectl edit configmap argocd-cm -n argocd

Add resource.exclusions, e.g.:

  1. apiVersion: v1
  2. data:
  3. resource.exclusions: |
  4. - apiGroups:
  5. - "*"
  6. kinds:
  7. - "*"
  8. clusters:
  9. - https://192.168.0.20
  10. kind: ConfigMap

The resource.exclusions node is a list of objects. Each object can have:

  • apiGroups A list of globs to match the API group.
  • kinds A list of kinds to match. Can be "*" to match all.
  • clusters A list of globs to match the cluster.

If all three match, then the resource is ignored.

In addition to exclusions, you might configure the list of included resources using the resource.inclusions setting. By default, all resource group/kinds are included. The resource.inclusions setting allows customizing the list of included group/kinds:

  1. apiVersion: v1
  2. data:
  3. resource.inclusions: |
  4. - apiGroups:
  5. - "*"
  6. kinds:
  7. - Deployment
  8. clusters:
  9. - https://192.168.0.20
  10. kind: ConfigMap

The resource.inclusions and resource.exclusions might be used together. The final list of resources includes group/kinds specified in resource.inclusions minus group/kinds specified in resource.exclusions setting.

Notes:

  • Quote globs in your YAML to avoid parsing errors.
  • Invalid globs result in the whole rule being ignored.
  • If you add a rule that matches existing resources, these will appear in the interface as OutOfSync.

SSO & RBAC

  • SSO configuration details: SSO
  • RBAC configuration details: RBAC

Manage Argo CD Using Argo CD

Argo CD is able to manage itself since all settings are represented by Kubernetes manifests. The suggested way is to create Kustomize based application which uses base Argo CD manifests from https://github.com/argoproj/argo-cd and apply required changes on top.

Example of kustomization.yaml:

  1. bases:
  2. - github.com/argoproj/argo-cd//manifests/cluster-install?ref=v1.0.1
  3. # additional resources like ingress rules, cluster and repository secrets.
  4. resources:
  5. - clusters-secrets.yaml
  6. - repos-secrets.yaml
  7. # changes to config maps
  8. patchesStrategicMerge:
  9. - overlays/argo-cd-cm.yaml

The live example of self managed Argo CD config is available at https://cd.apps.argoproj.io and with configuration stored at argoproj/argoproj-deployments.

Note

You will need to sign-in using your GitHub account to get access to https://cd.apps.argoproj.io